Cash In — Initialization

Start a debt settlement: the driver hands cash to the institution, and Presto reduces the driver's outstanding debt by that amount.

Overview

This is the first of the two Cash In steps. It:

• Re-validates the driver and the requested amount against the live outstanding_debt
• Reserves the amount so a second counter cannot settle the same debt concurrently
• Returns a transaction_reference and the driver details to display before collecting cash
• Returns a ttl after which the reservation is released automatically

No cash yet

Nothing is settled at this point and no money should change hands. The debt is reduced only by Cash In — Confirmation.

Endpoint details

Method: POST URL: /api/institutions/v1/drivers/debt/settlement/init Purpose: Reserve a debt settlement and obtain a transaction reference

Authentication required

All API calls require a valid bearer token. See Authentication.

Request specification

Headers

Header	Required	Description
Authorization	Yes	Bearer {token}
Content-Type	Yes	application/json
Idempotency-Key	Yes	UUID v4 identifying this logical operation. Enables safe replay.

Request parameters

Parameter	Type	Required	Description
driver	object	Yes	Container for driver identification information
driver.identifier_type	string	Yes	"phone" or "uid"
driver.identifier	string	Yes	The identifier value, in the format described in Driver Lookup
amount	number	Yes	Amount the driver is paying. Must be positive, at most outstanding_debt, up to 3 decimal places
currency	string	Yes	Currency code. Must match the balances.currency returned by lookup
institution_reference	string	Yes	Your identifier for this operation, so you can cross-reference it against your own records. Must be unique within your institution. 1–64 characters: letters, digits, hyphens and underscores
branch_reference	string	No	The institution's own branch or teller identifier, stored by Presto for reconciliation. Max 64 characters

Example request

// Headers:
// Authorization: Bearer {token}
// Content-Type: application/json
// Idempotency-Key: 8f14e45f-ceea-467a-9c2e-6f9a1b2c3d4e

{
  "driver": {
    "identifier_type": "phone",
    "identifier": "218920000000"
  },
  "amount": 200.000,
  "currency": "LYD",
  "institution_reference": "IZI-2026-0914-000187",
  "branch_reference": "TUN-CENTRE-VILLE-04"
}

Response specification

Success response

200 OK

{
  "data": {
    "status": "pending",
    "type": "debt_settlement",
    "transaction_reference": "DS-9F3K2LQ7XB",
    "institution_reference": "IZI-2026-0914-000187",
    "amount": 200.000,
    "currency": "LYD",
    "driver": {
      "uid": "10432",
      "name": "MOH... OK...",
      "phone": "218920000000"
    },
    "outstanding_debt_before": 340.500,
    "outstanding_debt_after_preview": 140.500,
    "ttl": "2026-09-14T18:49:51+00:00"
  }
}

Response fields

Field	Type	Description
status	string	Always "pending" for a successful init
type	string	Always "debt_settlement"
transaction_reference	string	Unique reference required by the confirm and status calls
institution_reference	string	Your own reference, echoed back unchanged
amount	number	Reserved amount, echoed back
currency	string	Currency of the amount
driver	object	Driver details to display for verification at the counter
outstanding_debt_before	number	Debt at the time of the reservation
outstanding_debt_after_preview	number	Debt that will remain once the transaction is confirmed
ttl	string	ISO 8601 timestamp when the reservation expires (15 minutes from init)

Error responses

403 Forbidden — settlement blocked for this driver

{
  "message": "Debt settlement is not allowed for this driver"
}

404 Not Found

{
  "message": "Driver not found"
}

409 Conflict — idempotency key reused with a different payload

{
  "message": "Idempotency key already used with a different payload"
}

409 Conflict — institution_reference already used

{
  "message": "Institution reference already used",
  "institution_reference": "IZI-2026-0914-000187",
  "transaction_reference": "DS-9F3K2LQ7XB"
}

422 Unprocessable Content — amount exceeds debt

{
  "message": "The amount may not be greater than the outstanding debt.",
  "errors": {
    "amount": [
      "The amount may not be greater than the outstanding debt."
    ]
  }
}

Error handling

Common errors

HTTP Status	Error Type	Example Message	When it Occurs / Resolution
401	Unauthorized	{"message": "Unauthenticated."}	Missing or invalid token.
403	Settlement blocked	{"message": "Debt settlement is not allowed for this driver"}	Debt settlement is blocked for this driver. Presto operations must clear it. Suspended drivers can still settle their debt.
404	Driver not found	{"message": "Driver not found"}	Identifier does not match a driver.
409	Idempotency conflict	{"message": "Idempotency key already used with a different payload"}	Generate a new key for a new operation.
409	Duplicate reference	{"message": "Institution reference already used", "transaction_reference": "..."}	You already initialized this operation. Continue with the returned transaction_reference rather than starting over.
422	Validation error	{"message": "The amount may not be greater than the outstanding debt.", "errors": { ... }}	Re-run lookup and retry with a valid amount.
500	Internal server error	{"message": "Failed to process request"}	Retry with backoff. No debt is settled by a failed init.

Implementation tips

Best practices

• Always run Driver Lookup immediately before init so the teller sees a current debt figure.
• Display the returned driver.name and amount to the driver and require an explicit acknowledgement.
• Store transaction_reference in your own records before calling confirm, so a crash between the two steps is recoverable.
• Show the teller a countdown for the 15-minute ttl.

Next steps

Collect the cash, then finalize with Cash In — Confirmation.